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ABSTRACT 

'I’his  document  describes  the  prototype  peer  review  capability  that  was  developed  as 
part  of  the  BR40  Repository  Integration  task.  The  peer  review  capability  uses  a  public 
domain  structure  editor  to  support  the  peer  ‘  review  of  Ada  source  code.  'I'he 
capability  includes  an  Ada  program  to  translate  Ada  source  in  ASCII  text  to  the 
intermediate  form  used  by  the  editor.  'I’he  editor  supports  embedding  peer  comments 
in  the  Ada  source  in  a  form  that  is  acceptable  to  an  Ada  compiler  and  processable  by 
a  SGML  parser. 

Besides  describing  the  source  peer  review  capability,  this  documents  contains 
recommendations  for  use  on  a  repository  and  for  productization. 
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PREFACE 

This  document  describes  the  fourth  and  fi»ial  version  in  the  series  of  prototypes  of  a 
peer  review  editor  for  Ada  source  code. 


Note:  The  contents  of  this  dcKument  are  available  in  electronic  form  from  a  STARS 
repository. 
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1.  SCOPE 

The  purpose  of  this  document  is  to  describe  the  prototype  peer  review  capability  for 
Ada  source  code  that  was  developed  as  part  of  BR40  Repository  Integration.  Besides 
describing  the  operation  of  the  prototype,  this  document  contains  information  related  to 
installation  on  a  repository  and  recommendations  for  further  work. 

One  objective  of  the  STARS  Program  is  to  institutionalize  peer  review  of  source  code 
and  technical  dtx:umentation  as  part  of  the  sy.stem  development  process.  This 
prototype  tool  tests  the  concept  of  a  folded  tree  editor  to  support  on-line  peer  review 
of  Ada  source  code. 

'I'he  capability,  named  AdaPTF.Rmacs  was  developed  from  a  public  domain  editor 
known  as  GNU  limacs  (GNU|.  'Ihe  tree  editing  functions  were  obtained  from  the 
University  of  Illinois.  Basic  descriptions  and  motivational  material  for  tree  rather  than 
language-sensitive  or  syntax-directed  editing  are  ctwered  by  jTRFn). 

Section  2  lists  referenced  documents;  Sectitni  3  de.scribes  the  prototype  operation  in  the 
form  of  a  user  guide;  and,  Section  4  contains  recommendations. 


Peer  Review  Capability  Description 
1)61.3-20850 


6 


STARS 


The  BOEING  Company 


CDRL  00850 


2.  REFERENCED  DOCUMENTS 

This  section  lists  all  documents  referenced  herein. 

[GNU]  "GNU  Emacs  Manual",  Fifth  Edition,  Emacs  Version  18,  October  1986, 
Richard  Stallman. 

[TREE]  '"I'he  'I’REEMACS  tree  editor  and  its  applications".  Computer  Science 
Department,  University  of  Illinois  at  Urbana-Champaign,  Samuel  Kamin  and 
David  Hammerslag,  Draft  January  5,  1989. 

|2ndj  "Ada  as  a  second  language",  Norman  H.  Cohen,  McGraw-Hill  Book 
Company,  1986. 
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3.  USER  GUIDE  TO  ADAPEERMACS  OPERATION 

3.1  Operational  Concept 

3.1.1  Basic  Notions 


The  basic  concept  underlying  .\daPEERmacs  is  the  notion  of  maintaining  the  Ada 
source  ctxie  and  peer  commentary  in  a  tree^based  intermediate  representation.  'I'he 
intermediate  representation  stores  nixies  as  a  single-rooted  pre-order  tree.  Each  node 
may  have  any  number  of  child  subtrees  and  represents  either  an  Ada  language 
construct  or  a  peer  commentary  construct. 


'I'he  di.splay  that  the  user  sees  uses  indentation  to  indicate  subtrees.  C!onstructs  with  the 
same  amount  of  indentation  are  all  siblings  or  cou.sins  of  siblings.  I'or  instance,  in  the 
code  fragment  show  below,  the  "with"  and  "procedure"  constructs  are  siblings  sharing  a 
"comment"  construct  as  their  parent.  'I’he  "while"  con.struct  is  a  cousin  to  "begin  — 
I.ine_.Sum"  since  their  parents  ("begin  —  Sum_AS(TI_C'ixie.s"  and  "function"  construct) 
are  siblings. 


—  This  is  page  458  from  Ada  as  a  [2nd|  l.ariguage 
with  Basic_K);  use  Basic_K); 
prixe^lure  .Sum„AS(.’II_C!odes  is 
Sum  :  Natural  :=  0; 

Length  :  Natural; 

Line  :  String(L.132); 

function  Line_.Sum  (Line  :  IN  String)  return  Natural  is 
Re.sult:  Natural  :=  0; 
begin  —  Line_.S'um 
for  i  in  Line'Range.lix)p 
Result  :=  Re.sult  -f  C’haracter'Pos(Line(i)); 
end  loop;  —  for  loop 
null; 

return  Result; 
end  Line_Sum; 
begin  —  .Sum_ASC’lI_Code.s 
while  NOT  l-nd_Of_r*ile  loop 
Gel_Linc(Line,  Length); 

Sum  :=  Sum  -f  Line_Sum(Line=>Line(L. Length)); 
end  loop;  —  while  loop 
Put(Sum); 

New_Line; 

end  Sum_AS('lI_Oodes;  —  procedure  body 
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The  major  difference  between  a  syntax-directed  editor  and  AdaPKERmacs  is  that 
AdaPEERmacs  does  not  require  that  the  tree  be  syntactically  and  semantically  correct 
Ada.  The  construct  insertion  functions  support  entering  the  correct  syntax  because  they 
use  a  strategy  of  user  prompting  and  template  insertion,  but  they  do  not  enforce  Ada 
syntax.  Syntactic  and  semantic  checks  are  user  initiated  by  invoking  a  command  that 
.sends  an  ASCII  representation  of  the  tree  io  an  Ada  compiler.  This  is  a  compromise 
between  the  minimal  support  that  an  experienced  Ada  programmer  would  desire  in  an 
editor  and  the  maximal  support  that  a  novice  Ada  programmer  would  receive  from  a 
.syntax-directed  editor. 

The  notion  of  a  folded  display  is  also  critical  to  comprehending  what  AdaPIi:ERmac.s 
puls  on  the  screen.  'I’he  AdaPEERmacs  display  may  hide  subtrees  just  as  if  .someone 
folded  a  piece  of  a  paper  to  cover  up  portions  of  printed  material.  The  text  below  is  a 
folded  version  of  the  code  fragment  previou.sly  displayed.  'I’he  text  for  "function 
I.ine_Sum"  and  the  statements  following  "begin  —  Sum_ASCH_C‘ode.s"  have  been 
folded  out  of  view. 

—  This  is  page  458  from  Ada  as  a  |2ndl  Language 
with  Basic_IO;  use  15asic_IO; 
procedure  Sum_/\SCTI_C!odcs  is 
Sum  :  .Natural  :=*  0; 

Length  :  Natural; 

Line  :  Slring(L.l32): 

function  Line_Sum  (Line  :  IN  String)  return  Natural  is 

end  Line_Sum; 

beein  —  Sum_AS(TI_C\)des 

end  Sum_ASC-II_C\)de.s;  —  procedure  body 

Storing  the  Ada  program  as  nodes  al.st)  permits  AdaPIiERmacs  to  maintain  other 
information  about  the  .source  code  besides  the  type  t)f  construct  each  node  repre.senls. 
Since  one  objective  for  this  prototype  is  support  of  peer  review,  AdaPEERMACS  al.so 
.stores  the  login  name  of  the  person  who  created  the  node,  the  login  name  of  the  person 
who  last  modified  the  node,  the  date  that  the  mnle  was  created,  and  the  date  that  the 
node  was  last  modified.  'I  his  administrative  information  is  automatically  displayed  for 
peer  comments  but  not  for  Ada  constructs.  1  lowever,  the  date  information  can  be  used 
to  .selectively  di.splay  either  Ada  or  peer  commentary  nodes  that  have  been  entered  or 
modified  after  a  specified  date.  Perhaps  this  administrative  information  vill  be  u.sed  in 
a  future  configuration  control  or  repo.sitorj  a.sset  management  application. 

'i'his  extra  information  AdaPEERmacs  is  maintaining  can  be  u.sed  to  .select  to  what  is 
displayed  on  the  screen.  In  the  current  version,  there  are  functions  that  permit  the  u.ser 
to  .selectively  display  (1)  all  nodes,  which  is  the  default:  (2)  only  Ada  nodes;  (3)  only 
Ada  PDL  nodes;  (4)  only  peer  commentary;  (5)  only  nodes  that  have  rntnlified  dates 
different  than  their  creation  dates:  or  (6)  tnily  nmles  whose  creation  or  mtxlification 


Peer  Review'  Capability  De.scription 
1)613-20850 


9 


STARS 


The  BOEING  Company 


CDRL  00850 


dale  is  later  than  a  user-specified  date.  Nodes  not  selected  for  display  appear  as 
blank  lines.  'ITiis  means  that  the  tree-point  cursor  (and  text  cursor)  will  .seem  to  .slop 
at  random  spots  when  cursor  motions  are  requested.  For  this  reason,  the  bottom  line 
of  the  AdaPF.HRmacs  display  gives  information  about  the  node  at  the  current  position. 

Furthermore,  since  the  GNU  Emacs  editor  upon  which  AdaPEERmacs  is  based  can 
display  .separate  windows,  AdaPEERmacs  also  provides  functions  to  automatically 
split  the  current  window  into  two  facing  windows  with  different  selective  displays. 
(Facing  windows  means  that  the  two  displays  appear  as  left-right  facing  pages  in  a 
b(H)k.)  Commands  that  invoke  tree  cursor  motion  will  automatically  invoke  cursor 
motion  in  all  facing  windows  so  that  the  pages  will  slay  line-aligned.  However,  this 
line  alignment  will  be  lo.si  if  tree-editing  commands  arc  invoked  in  any  facing  window. 
Because  of  the  ct)nlrt)l  that  the  l-macs  editor  exerts  over  display  of  updated  buffers,  the 
tree  cursor  po.silion  will  always  remain  correct  although  the  facing  display  may  not  be 
correct.  'I'hc  display  can  be  forced  to  slay  synchronized  with  the  tree  cursor  by 
requiring  keyboard  input  from  the  U-ser  as  each  facing  display  is  updated.  'I’he  current 
proU)lypc  docs  not  force  .<ynchronizalion. 

'I’he  text  below  is  an  example  of  two  facing  windows  where  the  left  .side  displays  only 
Ada  constructs  and  the  right  side  displays  only  peer  commentary.  (Note  example 
contains  where  elision  has  been  u.sed  in  order  to  fit  the  di.splay  on  the  page.) 


procedure  Sum__ASC . . . 
Sum  :  Natural  0; 


Length  :  Natural; 
Line:  Stringd.  .132)  ; 
function  Line_Sum. . . 
end  Line  Sum; 


{ —  I Peer_comment> 

I —  This  is  a  sample  comment 
I —  for  demonstratio.  purposes 
— |Created_By>  rojdavis 
1 — |Created_On>  Kon  Dec  18... 

I  —  |Last_Modified_Ey>mjdavis 
j — iLast_Modified_On>  Mon  Dec  18... 
[  —  I i Peer_comment> 

I 

I 

I 


3.1.2  Typical  Edit  Cycle 

'I'he  next  two  .sections  de.serihe  editing  starting  with  a  blank  display  and  .starling  with  a 
non-blank  display.  The  .symbols  "  before  a  character  means  the  u.ser  holds  down 
the  control  key  while  entering  the  next  character.  "I'hc  symbols  "M means  the  u.ser 
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enters  the  escape  key. 

Just  as  normal  editors  maintain  a  current  cursor  position  for  the  text  being  entered. 
AdaPlIERmacs  also  maintains  a  position  for  the  current  tree  node.  'iTie  current  text 
cursor  position  is  known  as  point  and  the  current  tree  position  is  known  as  tree-point. 

liach  node  of  the  tree  may  be  thought  of  as  a  separate  piece  of  text  with  its  own  point. 
CJNU  I:macs  refers  to  these  pieces  of  text  as  buffers.  GNU  Emacs  commands  that 
position  the  cursor  and  enter  text  within  a  buffer  are  scoped  within  the  text  of  the  node. 
I'or  example,  the  command  that  positions  the  text  cunsor  at  the  be^nning  of  a  buffer 
will  position  the  text  cursor  at  the  beginning  of  the  node's  text.  Twro  portions  of  a 
ntKle's  display  (its  label  and  end  label)  are  not  within  the  scope  of  the  node's  text. 
'ITiese  are  .synthesized  by  AdaPEERmacs  from  the  ntxle's  level  within  the  tree  (this 
allows  correct  indentation),  its  construct  name,  and  po.ssibly  admini.strative  information 
or  information  derived  from  its  parent  node.  'l*he  most  basic  construct  is 
ada-statement,  which  has  a  label  consisting  only  of  indentation  .spacing  and  a  clo.se 
label  of  Other  constructs  have  more  elaborate  labels  or  clo.se  labels.  I’or 

instance,  the  label  for  peer  comments  is  * — |Peer_comment>''  and  its  clo.se  label 
contains  all  the  administrative  information. 

3. 1. 2.1  Blank  Display 

Starling  with  a  blank  display,  the  goal  is  to  insert  Ada  constructs  to  create  an  Ada 
prtjgram. 

1 ,  Since  the  tree  representation  starts  with  a  single  r<K)t,  it  is  ctinvenienl  U»  begin 
by  inserting  an  Ada  comment.  'ITiis  is  acccomplished  by  entering  the  key 
sequence  '’(‘-cC-l-"  or  "M-x  ada-commenr.  AdaPE.ERmacs  will  create  a 
node  labeled  “ada-comment'',  will  update  the  display  with  3  lines  .starting  with 

"  and  then  position  the  text  cursor  at  the  middle  line  after  the  ’ITic 

nser  may  then  enter  text  for  the  comment. 

2.  'ITie  next  step  is  to  enter  an  Ada  construct.  'ITie  key  sequence  specifying  a 
template  ("C-cC'-i'')-  may  be  entered  followed  by  the  key  indicating  which 
template  is  desired  or  the  key  sequence  "M-x"  followed  by  the  desired  construct 
name  may  be  entered.  AdaPEIiRmacs  will  prompt  ft>r  the  information  ncx'ded 
to  fill  in  the  template  and  will  ask  if  the  template  is  to  be  inserted  as  nested  or 
not.  Responding  "y"  will  create  a  child  node  and  responding  'n"  wnl!  create  a 
sibling  node.  Since  the  tree  only  contains  a  nnil  node,  respond  "y”  to  create  a 
child  mxle.  N»)ie  that  one  template  may  generate  multiple  tree  mxles.  I-or 
instance,  the  ada  construct  ada-funclion-luxly  will  in.seri  a  node  for  itself,  an 
ada-declare  mxle  Tor  its  return  value  declaration,  an  ada -begin -noend  node, 
and  ada-siaiement  node  whose  text  is  "return  R1-SUI.T_NAME"  and  an 
ada -statement  ncxle  whose  text  is  "null".  'Hie  template  inserts  these  as  children 
or  sibling  nodes  as  is  appropriate  to  repre.senl  the  control  or  declaration  flow 
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each  construct  represents. 

3.  All  the  remaining  steps  repeat  the  template  invocation  (step  2).  There  are  key 
sequences  for  positioning  the  current  tree-point  where  the  user  desires  to  insert 
the  template.  "C-cC-yu"  moves  up  the  tree  -'ia  children  and  siblings; 
"C-cC-yd"  moves  down  the  tree  via  children  and  sibling  (depth-first  motion). 
Both  of  these  sequences  may  fold/unfold  the  display.  The  sequences 
"C-cC-yC'-u"  and  "C-cC-yC-d"  move  more  quickly  by  only  moving  sibling  to 
sibling  (breadth-first  motion). 

4.  The  editor  may  be  exited  and  the  file  saved  by  entering  C-xC-c. 

3. 1.2.2  Non-blank  Display 

Starting  with  a  non-blank  display  of  Ada  source,  the  goal  is  to  enter  peer  review 
comments. 

1.  The  first  step  is  to  position  the  tree-point  at  the  construct  to  which  the  comment 
will  apply.  "C-c('-yu"  moves  up  the  tree  via  children  and  siblings;  "C-cOyd" 
moves  down  the  tree  via  children  and  sibling  (depth-first  motion).  Both  of 
these  sequences  may  fold/unfold  the  display.  The  sequences  "OcOyCl-u"  and 
"Oc('-yOd"  move  more  quickly  by  only  moving  sibling  to  sibling 
(breadth-first  motion).  At  the  beginning  of  an  editing  ses.sion  the  tree-point  is 
positioned  at  the  root,  'riie  la.st  line  of  the  display  lists  the  construct  of  the 
tree-point  and  its  creation  date. 

2.  The  next  step  is  to  enter  an  ada-peer-commenl  construct.  The  key  sequence 
specifying  a  template  ("('-c(’-t?")  may  be  entered  or  the  key  sequence  "M-x 
ada-peer-comment"  may  be  entered.  AdaPliERmacs  will  put  the  label  and 
close  label  for  an  ada-peer-commenl  on  the  display  and  position  the  text 
cursor  after  a  middle  line  contain  " — ".  'I’he  text  for  the  comment  can  now  be 
entered.  I'wcry  time  a  "Return"  key  is  entered,  the  text  will  be  updated  with  a 
newline  containing  the  necessary  amount  of  indentation  space  and  a  " — ".  If  the 
tree-point  where  the  comment  is  to  be  inserted  is  an  ada-peer-comment  or 
already  has  a  child  that  is  an  ada-peer-commenl,  the  template  will  insert  a 
construct  known  as  ada-peer-followon.  This  allows  a  history  of  comments  to 
be  collected. 

3.  All  the  remaining  steps  repeal  the  steps  1  and  2. 

4.  The  editor  may  be  exited  and  the  file  saved  by  entering  C)-xC'-c. 
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3.2  Functionality 

3.2.1  Tree  editing  and  Motion  Functions 

The  tree  editing  commands  and  motion  functions  that  can  be  invoked  by  entering 
CTL-C  followed  by  CTL-Y  followed  by  the  key  identifying  the  function  are  (note  that 
they  can  also  be  invoked  by  M-x  followed  by  function  name): 

"p"  ! parent  —  Move  tree  cursor  (tree-point)  to  parent 

node 

"u"  !up  —  Move  tree  cursor  (tree-point)  to  next  node  up 
in  tree  (left  sibling  or  parent  node) 

"C-u"  ! up-condensed  —  Move  tree  cursor  (tree-point)  to 

parent  or  left  sibling  node 

"C-d"  ! down-condensed  —  Move  tree  cursor  (tree-point)  to 

right  sibling  node 

"d"  !down  —  Move  tree  cursor  (tree-point)  to  next  node 
down  in  tree  (child  or  right  sibling) 

"c"  ! child  —  Move  tree  cursor  (tree-point)  to  child  node 

"1"  lleft  —  Move  tree  cursor  (tree-point)  to  left 

sibling  node 

"r"  ! right  —  Move  tree  cursor  (tree-point)  to  right 

sibling  node 

"C-f"  ! char-right  —  move  text  cursor  1  character  to  right 
in  current  node 

"C-b"  ! char-left  —  move  text  cursor  1  character  to  left  in 
current  node 

"c-p"  ! previous-line  —  move  text  cursor  to  preceding  line 
in  current  node 

"c-n"  !  next-line  —  move  text  cursor  to  following  line  in 

current  node 

"C-1"  ! redraw-display  —  redraw  the  display 
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"T"  !goto-roo_t  —  move  tree  cursor  (tree-point)  to  tree 
root  node 

"e"  ! tree-edit-current-node  —  edit  the. subtree  rooted  at 
the  current  node  in  a  separate  window  (exit  by  entering 
M-C-c) 

"g"  !goto-node  —  go  to  a  specific  node 

" # "  ! set-tree-mark  —  set  the  value  of  mark 

! mark-current-node  —  remember  this  node  as  mark 

"M-u"  ! update  —  update  the  tree  with  all  changes 

"E"  ! show-all  —  Make  the  display  show  all  the  nodes 

"A"  !show-ada  —  Make  the  display  show  only  Ada  nodes 

"P"  ! show-adl  —  Make  the  display  show  only  Ada  pdl  nodes 

"C"  ! show- comments  —  Make  the  display  show  only  peer 

comments 

"M"  !  show-modified  —  Make  the  display  show  only  nodes 

whose  modified  date  is  not  the  same  as  created  date 

"D"  !  show-after  —  Make  the  display  shov7  only  nodes 

whose  created  or  modified  date  is  after  a  specified  date 

"FE"  ! face-all  —  Split  the  current  window  into  two  facing 
separate  windows  and  display  all  the  nodes  in  the  new  window 
(exit  by  entering  M-C-c) 

"FA"  ! f ace-ada  —  Split  the  current  window  into  two  facing 
separate  windows  and  display  only  ada  nodes  in  the  new  window 
(exit  by  entering  M-C-c) 

"FP"  !face-adl  —  Split  the  current  window  into  two  facing 
separate  windows  and  display  only  ada  PDL  nodes  in  the  new 
window  (exit  by  entering  M-C-c) 

"FC"  ! face-comments  —  Split  the  current  window  into  two 
facing  separate  windows  and  display  only  peer  commentary 
nodes  in  the  new  window  (exit  by  entering  M-C-c) 
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"FM"  ! face-modified  —  Split  the  current  window  into  two 
facing  separate  windows  and  display  only  modified  nodes  in 
the  new  window  (exit  by  entering  M-C-c) 

"FD"  ! face-after  —  Split  the  current  window  into  two 
facing  separate  windows  and  display  only  nodes  created  or 
modified  after  a  specified  date  in  the  new  window  (exit  by 
entering  M-C-c) 

Other  motion  and  tree  editing  commands  that  are  only  invoked  by  M-x  followed  by 
function  name  are: 

! delete-tree  —  delete  the  current  node  and  its  subtree 

!  read-over-root  —  replace  the  root  node  with  the  specified 
tree  from  a  file 

!write-tree  —  write  the  entire  tree  to  disk  in  both  an  ascii 
Ada  format  and  its  intermediate  AdaPEERmacs  format 

! read-child  —  read  a  tree  from  a  file  and  add  it  as  a  child 
subtree  of  the  current  node 

! write-subtree  write  the  tree  rooted  at  the  current  node  to 
disk  in  both  an  ascii  Ada  format  and  its  intermediate 
AdaPEERmacs  format 

! tree-kill  —  delete  the  subtree  rooted  at  the  current  node, 
saving  it  for  later  yanking. 

! tree-yank  —  add  a  copy  of  the  most  recently  killed  tree  as 
a  subtree  to  the  current  node 

Node  text  motion  commands  that  may  be  invoked  by  the  following  identifying  key 
sequence  (or  by  entering  M-x  followed  by  function-name)  are: 

"M-<"  ! beginning-of-node  —  move  text  cursor  to  beginning  of 

node's  text 

"M->"  !end-of-node  —  move  text  cursor  to  end  of  node's  text 
"C-b"  ! backward-char  —  move  text  cursor  1  character  to  left 
"C-f"  ! forward-char  —  move  text  cursor  1  character  to  right 
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"C-p"  ! previous-line  —  move  text  cursor  to  preceding  line 

"C-n"  ! next-line  —  move  text  cursor  to  following  line 

"C-a"  display-pretty-printed  —  show  the  entire  tree  as  an 
ascii  file  in  a  separate  window 

3.2.2  Other  Useful  Functions 

Other  useful  functions  that  are  invoked  by  entering  a  specific  key  sequence  or  by 
entering  M-x  followed  by  function-name  are: 

"C-a"  display-pretty-printed  —  show  the  entire  tree  as  an 
ascii  file  in  a  separate  window 

"C-g"  quit  —  discard/abort  current  command 

"C-hC-h"  help-for-help  —  display  an  explanation  of  help 
functions  available 

"C-xo"  other  window  —  move  to  the  next  window  (that's  a 
letter  o  not  a  number  0) 

"C-xl"  delete-other-windows  —  close  all  windows  but  the 
window  where  the  cursor  is  located  (that's  a  number  1  not  a 
letter  1) 


"C-xC-f"  find-file  —  find  a  file  (and  open  it  for  display) 

"C-xC-c"  save-buf fers-kill-emacs  —  offer  to  save  each 
modified  file  and  then  exit. 

3.2.3  Templates 

All  templates  are  invoked  by  entering  CTRL-c  followed  by  C'l’RI.-t  followed  by 
template  identifier  key. 

"h"  ada-header 

"-"  ada-comment 

"C-a"  ada-array 

"A"  ada-accept 


Peer  Review  Capability  Description 
1)61.3-20850 


16 


STARS  The  BOEING  Company 


"a" 

ada-stmt 

"b" 

ada-exception-block 

"D" 

ada-declare-block 

"d" 

ada-declare-stmt 

"c" 

ada-case 

"C-e" 

ada-elsif 

"e" 

ada-else 

"C-k" 

ada-package-spec 

"k" 

ada-package-body 

"C-n" 

ada-entry 

"C-p" 

ada.-procedure-spec 

"P" 

ada- subprogram- body 

"C-f" 

ada- function-spec 

"f" 

ada-for-loop 

"i" 

ada-if 

"1" 

ada-loop 

"o" 

ada-or 

"C-r" 

ada-record 

"C-s" 

ada-subtype 

"s" 

ada-select 

"S" 

ada-separate 

"C-t" 

ada-task-spec 

"t" 

ada-task-body 
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"C-y" 

"C-u" 

"C^v" 

"C-w" 

"w" 

"C-x" 


X 


7 


"  I  " 


ada-type 

ada-with-use 

ada-private 

ada-when 

ada-while-loop 

ada-exception 

ada-exit 

ada-pdl 

ada-peer-comment 

ada-peer-response 
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4.  RECOMMENDATIONS 

4.1  Lessons  Learned 

4.1.1  Regarding  GNU  Emacs 

Our  expectations  regar.-,.u;  extensibility  and  power  of  GNU  Emacs  were  fulfilled. 
Adding  new  co'^imai"  >  l  T.iing  commands  to  keystroke  combinations,  replacing 
commands,  and  ad'."  .c  'e’i  .  lew  commands  are  all  relatively  simple  modifications. 
However,  the  buffer/wu.d.  •,  metaphor  that  GNU  Emacs  uses  is  not  as  conducive  to 
facing  page  editing  as  we  .oped,  but  we  used  Emacs'  extensibility  to  overcome  most  of 
the  problems. 

The  remaining  problem  *  ...  the  ;»mount  of  control  GNU  Emacs  exerts  over  display 

updating  intcri'erc.s  ..ith  kc  ping  the  iV.cing  displays  synchronized  as  a  user  scrolls.  The 
display  may  not  bo  updated  to  reflect  the  actual  cur.sor  position.  Requiring  keyboard 
input  from  the  use''  in  the  form  of  question-response  can  force  the  update,  but  other 
informational  messages  may  mask  the  questions.  The  user  can  also  force  an  update  by 
switching  to  the  facing  display  and  requesting  a  display  update.  Perhaps  it  would  be 
better  U)  abandon  the  concept  of  automatically  keeping  the  facing  displays  synchronized 
and  leave  display  scrolling  en.irely  to  the  user.  'I'his  solution  is  the  one  used  by  high 
performance  workstations  that  provide  multiple,  simultaneous  editing  sessions  on  the 
same  file  by  the  same  user. 

4.1.2  Regarding  Structure  Editing 

The  l.imac;.  extensions  we  used  from  .'.oftware  furnished  by  the  University  of  Illinois 
['PRF.EI  prt  .'ided  the  basic  capability  fv^r  editing  the  Ada  source  code  as  a  tree  of  Ada 
language  constructs.  Since  checking  conformance  of  the  Ada  source  code  to  c...  -ect 
syntax  and  semantics  is  not  part  of  structure  editing,  .selecting  the  optimum  Ic'cl  of 
abstraction  for  the  Ada  language  constructs  was  the  most  difficult  task.  We  chose  the 
level  of  abstraction  that  is  used  by  prettypr inters  (flow  of  control  and  declarations). 
Whether  this  is  optimum  or  not  will  have  to  be  tested  by  deployment. 

Structure  editing  has  some  similarity  with  context  sensitive  editing  (such  as  DIANA 
supports)  in  that  the  editor  is  maintaining  information  about  the  structure.  The 
software  provided  by  the  University  of  Illinois  enabled  us  to  also  associate 
administrative  information  with  each  construct  represented  in  the  tree.  'I’hus,  we  were 
able  to  customize  the  editor  to  selectively  display  only  certain  construct:  (Ada,  Ada 
comments,  peer  comments,  etc)  and  U)  selectively  display  by  creation  and  modification 
dates  and  user  identification.  'Phis  information  would  be  relevant  to  tools  that  were 
responsible  for  access  control  and  configuration  or  asset  management.  If  the  S'lARS 
infrastructure  were  to  be  standardi'zed  on  DIANA  or  IRIS  as  an  intermediate 
representation,  it  would  be  useful  if  the"  editor  supporting  the  intermediate 
representation  also  automatically  collected  the  administrative  information. 
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4.1.3  Regarding  Editor  Presentation 

AdaPEERmacs  implements  several  techniques  in  its  display: 

explicit  structure  presentation, 
selective  presentation, 
folded  page  presentation,  and 
facing  page  presentation. 

We  mimicked  the  indentation  style  of  prettyprinters  to  reveal  the  structure  of  the  Ada 
source  code.  It  seemed  most  comfortable  for  an  experienced  programmer.  This 
choice  also  let  us  partially  support  some  of  the  Ada  syntactic  rules  as  an  aid  to  novice 
programmers  v^hile  not  constraining  experts.  I  person  entering  code  should  be  able  to 
concentrate  on  the  "what"  of  the  program  bei;  built  rather  than  on  the  "what"  of  the 
Ada  syntax.  Most  of  the  syntactic  support  is  b^'ing  provided  by  the  st?”'t  and  end  labels 
provided  for  each  construct.  Beginning  keywords,  such  as  "loop",  are  usually  assigned 
as  the  start  label.  The  Ada  statement  terminating  along  with  ending  keywords  are 
usually  assigned  as  the  end  label.  The  only  subtlety  in  creating  this  type  of  indented 
structure  presentation  is  the  correct  display  of  nested  control  such  as  loops  within 
loops. 

Sini.e  structure  editing  requires  an  intermediate  form  wherein  information  about  the 
structure  is  stored,  selective  pre.sentation  is  easily  implemented.  The  major  decision 
relative  to  selective  presentation  is  the  treatment  of  material  not  to  be  displayed.  We 
cho.se  to  use  blank  lines  and  provide  feedback  to  the  user  as  to  cursor  position.  'I'his  is 
particularly  usef  -i  when  the  cursor  is  stopped  over  blanked  out  areas.  I'liis  choice  was 
made  in  order  to  lacilitate  facing  page  presentation 

'I’he  folded  page  presentation  is  also  a  direct  consequeiKe  of  tree  editing.  It  can  be 
disconcerting  at  first  when  a  command  to  scroll  radically  changes  the  display. 
Mowever,  this  confusion  is  easily  removed  when  the  folded  concept  is  explained.  We 
increased  the  utility  of  the  folded  page  presentation  by  providing  tw  '•  oi  scroll 
commands.  One  sets  scrolls  the  tree  in  a  depth-first  fashion  (unfolds;  ••nu  uiC  other 
set  scrolls  the  tree  in  a  breadth-first  fashion  (does  not  unfold).  'I'hi.-.  gives  the  user  a 
choice  in  the  level  of  detail  displayed,  l^olded  page  presentation  should  be  even  more 
useful  in  document  preparation  and  review  because  it  effectively  lets  the  user  scroll  an 
outline  t)f  the  document. 

We  u.sed  the  capabilities  of  GNU  limacs  for  .splitting  a  terminal  display  into  .several 
screens  to  implement  the  facing  page  presentation.  I'acing  page  pre.sentation  is 
basically  a  technique  for  visually  .synchronizing  selective  displays.  It  is  mo.st  effective 
w-ien  one  page  displays  all  material  and  the  other  displays  selected  material.  We 
succeeded  in  auU)matically  keeping  the  displays  .synchronized  most  of  the  time..  More 
in-depth  knowledge  of  GNU  Emacs  I/O  handling  would  be  required  to  achieve 
.synchronization  all  the  time.  'I’he  blank  line  style  we  chose  for  selective  display  works 
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well  for  facing  page  presentation  of  Ada  source  on  one  side  and  peer  comments  on  the 
other  because  the  comments  are  only  associated  with  a  few  lines  of  text.  (Refer  to  page 
10  for  an  example  of  this  style.)  This  may  not  be  satisfactory  for  peer  comments  in 
documents.  A  more  elaborate  scheme  that  put  the  peer  comment  on  tlie  facing  page 
line  that  is  parallel  to  the  top  of  the  corresponding  document  element  (section,  chapter, 
paragraph,  etc.)  would  be  better.  It  would  also  insert  blank  lines  after  the  document 
clement  if  the  peer  comment  required  more  lines  than  the  document  element  used.  This 
style  is  illustrated  below: 

Section  x.y  Recommendations 

In  light  of  the  new. . . 
we  recommend  purchase. 

We  also  recommend  purchase  of 
a  maintenance  contract  from 
the  same  company. 

4.2  Suggestions  for  .Repository  Installation 

’I'he  prototype  currently  is  ba.sed  on  a  BSD  4.2  version  of  GNU  limacs.  Installation 
and  trial  use  at  the  .S'l'ARS  repository  would  require  porting  the  prototype  to  an 
existing  VMS  GNU  limacs  impleme:  lation.  It  would  also  be  useful  to  "bytecompile" 
as  much  of  the  modifications  as  po.v.ible  to  improve  its  performance.  (Most  of  the 
modifications  are  currently  being  ''interpreted"  by  the  GNU  editor.) 

It  would  also  be  desirable  to  put  a  user-friendly  "shell"  around  the  editor  invocation 
that  would  make  the  translation  to  intermediate  form  and  back  again  invisible  to  a 
user.  Some  of  this  could  be  provided  by  GNU  limacs  modifications  and  some  by  an 
operating  system  command  script. 

4.3  Suggestions  for  Further  Work 

More  Work  is  needed  in  replacing  the  standard  editor  commands  to  correctly  function 
within  a  tree  node's  text.  More  work  is  also  needed  in  checking  that  the  deletion  and 
copying  of  subtrees  works  correctly.  Presumably  these  functions  were  provided  by  the 
code  received  from  the  University  of  Illinois,  but  we  have  not  tested  them. 

A  version  that  provided  peer  review  entry  for  SGMl.-tagged  documents  would  alst)  be 
useful.  Such  an  editor  would  support  creation  of  SGMl.-tagged  documents  while 
hiding  the  cumbersome  tags  from  the  user's  view.  The  start  and  end  labels  could  be 
used  for  a  limited  type  of  WYSIWYG  ("What  You  See  Is  What  You  Get") 
pre.sjntation.  Also,  it  would  be  beneficial  to  implement  the  more  elaborate  form  of 
facing  page  pre.scntation  discussed  in  section  4.1.3  above. 


These  are  not  new  features. 
They  are  available  from  Ajax 
Software  at  a  cheaper  price." 

In-house  maintenance  would  be 
cheaper  and  as  good. 


21 


Peer  Review  Capability  Description 
1)613-20850 


The  B06ing  company 


D6 I 3-20850 


00 


1)613-20850 


23 


